fix(mcp): contribute Connect an Agent into the Account app nav so a non-admin can mint their own key - #17646

Fixes #16746

Clause-②: no

_{Declared by the dispatching domain:cli PM seat (session session_01TSf4DV7ziu4V5j73e46b7c), matching the claim comment on #16746. Verified against the DIFF: the payload gains one array ELEMENT of an existing shape, not a new key — NavigationContributionSchema is untouched and both contributions parse against the real contract (pinned in this PR). 0 new error codes. The permission-VISIBILITY aspect is deliberately not clause-②: a runtime permission/security behaviour change sits on the manual floor, and that floor was discharged by the maintainer ruling of 2026-09-08 (decision batch #85, option A, verbatim 「其他同意」), not by this declaration.}

What changed

CONNECT_AGENT_UI_BUNDLE (packages/mcp/src/connect-ui.ts) now carries a second
navigationContributions entry, the near-twin of the existing one, targeting the account
app's grp_account_developer group. The Setup entry is byte-unchanged, so admins keep the page
where the shipped guide and the runtime's own error text point.

app: 'account' · group: 'grp_account_developer' · priority: 200
items: [{ id: 'nav_connect_agent', type: 'page', pageName: 'connect_agent',
          label: 'Connect an Agent', icon: 'bot' }]

Nothing else moves: no backend change, no authorization change, no change to which permissions
exist, no gate added or removed anywhere, and packages/platform-objects is targeted by name,
never edited. Executes the recorded ruling (option A, director seat decision batch #85,
2026-09-08, maintainer verbatim 「其他同意」).

Why this shape and not the others — each refused on measurement

A navigation contribution registers exactly when the page registers, which is why both
entries live in this one bundle and neither carries a gate of its own — an opted-out deployment
still gets no page and neither entry.

The item-id question, answered from the fold

Both entries deliberately share the item id nav_connect_agent. That is scoped, not a
collision, read off SchemaRegistry rather than assumed: contributions are keyed by target
app (appNavContributions, a Map keyed by app name) and applyNavContributions(app) consults only
get(app.name), so a nav item id is unique within one app's navigation tree. Nothing indexes
it across apps — no id-keyed registry, no de-duplication by id — and the translation bundles are
keyed apps.APP.navigation.NAV_ID, which makes one shared id two distinct keys. One destination
keeps one identity.

The two items are separate object literals rather than one shared const: the fold
structuredClones the app but pushes ...c.items by reference, so a shared literal would
sit in two apps' navigation trees at once.

Acceptance — both halves measured over the real composition

Real SETUP_APP / ACCOUNT_APP / SETUP_NAV_CONTRIBUTIONS, the real
CONNECT_AGENT_UI_BUNDLE, the real fold and the real RBAC-by-route filter (RestServer with
this repo's established stub-the-exec-context pattern from
packages/rest/src/meta-app-publish-gate.test.ts), driven from packages/cli — the one package
that depends on all four:

⚠️ Declared, not hidden: that measurement was a scratch file, run once and deleted — it is
not committed. packages/mcp declares no dependency on @objectstack/rest,
@objectstack/objectql or @objectstack/platform-objects, so a permanent both-halves pin cannot
live inside this PR's declared file surface, and this file deliberately does not reimplement the
fold or the filter. See Acceptance notes for where that pin belongs.

The committed pin, and proof it can fail

packages/mcp/src/connect-agent-account-nav.test.ts (7 tests) pins the half this package owns:
the contribution aims at the ungated app and group; its item carries nothing the server-side nav
filter could strip for a permissionless caller (requiredPermissions / requiresService /
visible); the Setup entry is byte-unchanged; both contributions parse against the real
NavigationContributionSchema; and — the load-bearing one — the bundle declares no permission
key anywhere and no apps collection, so it cannot reach the card by widening Setup instead.

Two ablations, each committed-first, proven on disk, and restored with git checkout HEAD --
verified by hash equality against the HEAD blob plus an empty git diff HEAD:

⚠️ A first attempt at leg A deleted the whole contribution block and produced a parse error,
so the test never ran — a void reading, recorded rather than quietly retried, and replaced by the
parse-safe A2 above.

Acceptance notes

• ⚠️ Where the permanent both-halves pin belongs: packages/cli/test/. Read from
  package.json, packages/cli is the only workspace package depending on @objectstack/mcp,
  @objectstack/rest, @objectstack/objectql and @objectstack/platform-objects at once —
  the same argument packages/cli/scripts/check-app-nav-i18n.mjs makes in its own header for
  living there ("cli is the composition root … the ONLY workspace package that depends on all
  eleven Setup nav contributors at once"). It is outside this PR's declared file surface and
  packages/cli/** has siblings in flight this round, so it is reported rather than taken.
• node packages/cli/scripts/check-app-nav-i18n.mjs passes (10 contributors, 54 merged setup
  nav ids, 4 locales). Measured reason it is silent on the new entry: the gate scopes itself to
  APP_NAME = 'setup' and continues on any contribution whose app differs, so it demands no
  translation key for a contributed account item. Consequence, noted: no
  apps.account.navigation.nav_connect_agent label exists in any locale, so the entry renders its
  English literal under zh-CN / ja-JP / es-ES while the Setup twin renders translated. Those
  keys live in packages/platform-objects/src/apps/translations/ — outside this surface.
  app-nav-translation-parity.test.ts cannot see it either (it walks statically declared nav
  only, and asserts the reverse direction for STUDIO_APP alone).
• The runtime text this card was raised on — packages/mcp/src/plugin.ts:372 and
  packages/mcp/README.md:92, both directing users to "Setup → Connect an Agent" — becomes true
  for non-admins with this change and needs no edit. Recorded so nobody files it twice.
• Deferred option C (a per-user "My API keys" panel) does not collide and keeps its whole
  scope: C authors a new panel, this adds a second nav entry to the existing page, and
  account.app.ts already ships nav_account_api_keys in the exact group targeted here.
• Premise shift, declared: the card's urgency paragraph says the OAuth self-service path "is
  currently blocked by MCP OAuth cannot complete on 17.3.0: plugin-auth passes validAudiences, which @better-auth/oauth-provider 1.7.2 no longer reads — every resource= request fails with invalid_target … is not configured #16530 and narrowed by OAuth-connected MCP agents run under the mcp_agent_data_* ceiling ∩ user, not "as yourself": a viewAllRecords manager sees 5 accounts / 0 opportunities over OAuth vs 9 / 23 over an API key #16549". Both are now closed, so that half of the
  argument has expired. The ruling does not rest on it — it rests on API keys being per-user
  credentials — and re-grading is triage's, not this PR's.
• ⚠️ main moved under this branch and brought a breaking retirement whose name collides with
  the shape used here: feat(spec)!: retire the type: 'page' list-view mount and its pageName binding #17298, "retire the type: 'page' list-view mount and its pageName
  binding". Read rather than assumed — it touches packages/spec/src/ui/view.zod.ts, not
  app.zod.ts, its own FROM → TO table prescribes "reach the page from the app's navigation:
  { id: 'nav_sales_home', type: 'page', pageName: 'sales_home', label: 'Sales' }" as the
  replacement, it calls PageNavItem.pageName "the page mount that has always rendered", and it
  states that the nav twin validateNavTargetRefs is untouched. origin/main is merged in here
  and the affected slice was re-verified on the merge result.

Gates

58 families derived on the final diff with
node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack, each run with
output redirected and $? captured before any pipe, then reconciled with --ran:

Run reconciliation — 58 derived, 57 run, 1 NOT-MEASURED, 0 UNRUN.
  NOT-MEASURED · DERIVED (1) — pnpm check:dual-build-cjs-loads
    [recorded exit 3 on line 38 — PREREQUISITE NOT MET]

check:dual-build-cjs-loads refused its own prerequisite: it reads built output and 12 packages
outside this diff's closure have no dist (@objectstack/studio, @objectstack/client-react,
the four connectors, …). Its own text says so — "⛔ This is NOT a pass: nothing was measured."
It needs a repo-wide pnpm build, which is CI's run; CI checks out and builds fresh. NOT
MEASURED, recorded as neither green nor red.

Plus the two the tool does not name: pnpm lint — run repo-wide to completion
(eslint . --no-inline-config, 2m24s, exit 0), so no narrowing was claimed — and
node packages/cli/scripts/check-app-nav-i18n.mjs (exit 0, verdict line quoted above).

Receiving package, re-run on the merge result: pnpm --filter @objectstack/mcp test — 30 files,
320 tests passed — and pnpm --filter @objectstack/mcp typecheck. The new test file is proven to
be in the type-checked program rather than assumed: tsc -p tsconfig.test.json --listFiles
counts it 1 (and 0 in the main program, which is tsconfig.json's own exclude, unchanged).
packages/spec moved on the incoming side, so pnpm --filter @objectstack/spec build && check:generated ran on the merge result too.

Every heavy run went through scripts/pm/os-verify-lock.sh with OS_VERIFY_LOCK_SLOT=issue-16746.

维护者速读(草稿)

改了什么 — 「连接智能体」这个页面,以前只在「系统设置」里有入口。现在在每个人自己的
「账户 → 开发者」里也加了一个入口,就挨着已经在那里的「API 密钥」。设置里那个入口原样保留,
管理员看到的东西一点没变。

为什么改 — 我们对外说的是「Claude 只能看到和操作您自己有权限的数据」,而后台本来就是
「谁调用就发给谁」。但界面上只有管理员能走到那个按钮,所以普通销售、销售经理照着指南操作,
第一步就卡住了。运行时自己报的错误消息也在把他们指向一个打不开的页面。维护者 9 月 8 日已裁决
按这个方向做(路线 A)。

风险与代价(含回滚) — 后台、授权、对外承诺一个字都没动,没有新增或删除任何权限开关。
唯一的变化是「账户」应用里多了一个菜单项。已实测:没有任何权限的用户现在能看到这个菜单项,
而「系统设置」对他仍然是 403 拒绝——这两件事同时成立,是本次验收的全部内容。回滚就是删掉那
一个对象字面量,一次 revert,无数据迁移、无兼容包袱。⚠️ 一个小缺口:这个新菜单项目前没有
中文/日文/西班牙文标签(翻译文件在另一个包里,不在本 PR 范围),所以在非英文界面下它会显示
英文原文。不影响功能。

席位意见 — (留空,待席位定稿)

你要做的 — 只需确认一件事:把「连接智能体」放进每个人自己的账户页,而不是继续只放在管理员
的系统设置里,符合你 9 月 8 日的裁决意图。其余都是机械落地。

Generated by Claude Code

Generated by Claude Code